Function Reference

_AD_GetObjectsInOU

Returns a filtered array of objects and attributes for a given OU or just the number of records if $bCount is True.

#Include <AD.au3>
_AD_GetObjectsInOU($sOU[, $sFilter = "(name=*)"[, $iSearchScope = 2[, $sDataToRetrieve = "sAMAccountName"[, $sSortBy = "sAMAccountName"[, $bCount = False]]]]])

Parameters

$sOU	The OU to retrieve from (FQDN) (default = "", equals "search the whole AD tree")
$sFilter	Optional: An additional LDAP filter if required (default = "(name=*)")
$iSearchScope	Optional: 0 = base, 1 = one-level, 2 = sub-tree (default)
$sDataToRetrieve	Optional: A comma-seperated list of attributes to retrieve (default = "sAMAccountName"). More than one attribute will create a 2-dimensional array
$sSortBy	Optional: name of the attribute the resulting array will be sorted upon (default = "sAMAccountName"). To completely suppress sorting (even the default sort) set this parameter to "". This improves performance when doing large queries
$bCount	Optional: If set to True only returns the number of records returned by the query (default = "False")

Return Value

Success: Number of records retrieved or a one or two dimensional array of objects and attributes in the given OU. First entry is for the given OU itself
Failure: "", sets @error to:
    1 - Specified OU does not exist
    2 - No records returned from Active Directory. $sDataToRetrieve is invalid (attribute may not exist). @extended is set to the error returned by LDAP
    3 - No records returned from Active Directory. $sFilter didn't return a record

Remarks

Multi-value attributes are returned as string with the pipe character (|) as separator.

The default filter returns an array including one record for the OU itself. To exclude the OU use a different filter that doesn't include the OU
e.g. "(&(objectcategory=person)(objectclass=user)(name=*))"

To make sure that all properties you specify in $sDataToRetrieve exist in the AD you can use _AD_ObjectExistsInSchema.

The following examples illustrate the use of the escaping mechanism in the LDAP filter:
(o=Parens R Us \28for all your parenthetical needs\29)
(cn=*\2A*)
(filename=C:\5cMyFile)
(bin=\00\00\00\04)
(sn=Lu\c4\8di\c4\87)
The first example shows the use of the escaping mechanism to represent parenthesis characters.
The second shows how to represent a "*" in a value, preventing it from being interpreted as a substring indicator.
The third illustrates the escaping of the backslash character.
The fourth example shows a filter searching for the four-byte value 0x00000004, illustrating the use of the escaping mechanism to
represent arbitrary data, including NUL characters.
The final example illustrates the use of the escaping mechanism to represent various non-ASCII UTF-8 characters.

Related

_AD_GetAllOUs

Example

#AutoIt3Wrapper_AU3Check_Parameters= -d -w 1 -w 2 -w 3 -w 4 -w 5 -w 6
#AutoIt3Wrapper_AU3Check_Stop_OnWarning=Y
#include <AD.au3>

; Open Connection to the Active Directory
_AD_Open()
If @error Then Exit MsgBox(16, "Active Directory Example Skript", "Function _AD_Open encountered a problem. @error = " & @error & ", @extended = " & @extended)

; Get FQDN for the currently logged on user
Global $sFQDN = _AD_SamAccountNameToFQDN()

; Strip off the CN
Global $iPos = StringInStr($sFQDN, ",")
Global $sOU = StringMid($sFQDN, $iPos + 1)

Global $aObjects[1][1]

; *****************************************************************************
; Example 1
; Get the OU the current user is assigned to.
; Then get an unfiltered list of all objects in this OU.
; *****************************************************************************
$aObjects = _AD_GetObjectsInOU($sOU, "(name=*)", 2, "sAMAccountName,distinguishedName,displayname")
If @error > 0 Then
MsgBox(64, "Active Directory Functions - Example 1", "No OUs could be found")
Else
_ArrayDisplay($aObjects, "Active Directory Functions - Example 1 - Objects in OU '" & $sOU & "'")
Global $iResult = _AD_GetObjectsInOU($sOU, "(name=*)", 2, "sAMAccountName,distinguishedName,displayname", "", True)
MsgBox(64, "Active Directory Functions - Example 1", "This example returned " & $iResult & " records")
EndIf

; *****************************************************************************
; Example 2
; Get the OU the current user is assigned to.
; Then get a filtered list of all users in this OU that start with the first
; letter of the current user. Sort the result by displayname.
; *****************************************************************************
Global $sUser = StringLeft(@UserName, 1)
$aObjects = _AD_GetObjectsInOU($sOU, "(&(objectcategory=person)(objectclass=user)(cn=" & $sUser & "*))", 2, "sAMAccountName,distinguishedName,displayname", "displayname")
If @error > 0 Then
MsgBox(64, "Active Directory Functions - Example 2", "No OUs could be found")
Else
_ArrayDisplay($aObjects, "Active Directory Functions - Example 2 - Objects in OU '" & $sOU & "'")
EndIf

; *****************************************************************************
; Example 3
; Use ANR (Ambigous Name Resolution) to get all objects with the same given Name
; as the current user in the ANR-supported attribute fields.
; Searches the whole domain.
; *****************************************************************************
Global $sGivenName = _AD_GetObjectAttribute(@UserName, "GivenName")
$aObjects = _AD_GetObjectsInOU("", "(ANR=" & $sGivenName & ")", 2, "sAMAccountName,distinguishedName,displayname", "displayname")
If @error > 0 Then
MsgBox(64, "Active Directory Functions - Example 3", "No objects found")
Else
_ArrayDisplay($aObjects, "Active Directory Functions - Example 3 - Ambigous Name Resolution. Search for '" & $sGivenName & "'")
EndIf

If MsgBox(36, "Active Directory Functions", "Would you like to see further examples using extended LDAP queries?") <> 7 Then
$sOU = ""
; ********************************
; User accounts that do not expire
; ********************************
_Examples("(&(objectCategory=person)(objectClass=user)(|(accountExpires=9223372036854775807)(accountExpires=0)))", "sAMAccountName,distinguishedName,displayname", "User accounts that do not expire")
; ****************************
; User accounts that do expire
; ****************************
_Examples("(&(objectCategory=person)(objectClass=user)(!accountExpires=9223372036854775807)(!accountExpires=0))", "sAMAccountName,distinguishedName,displayname,accountexpires", "User accounts that do expire")
; ***************************************
; User accounts that already have expired
; ***************************************
Global $sAD_DTExpire = _Date_Time_GetSystemTime() ; Get current date/time
$sAD_DTExpire = _Date_Time_SystemTimeToDateTimeStr($sAD_DTExpire, 1) ; convert to system time
Global $iAD_DTExpire = Int(_DateDiff("s", "1601/01/01 00:00:00", $sAD_DTExpire) * 10000000) ; convert to Integer8
_Examples("(&(objectCategory=person)(objectClass=user)(!accountExpires=9223372036854775807)(!accountExpires=0)(accountExpires<=" & $iAD_DTExpire & ")", "sAMAccountName,distinguishedName,displayname", "Expired user accounts")
; *************************************
; Users not required to have a password
; *************************************
_Examples("(&(objectCategory=person)(objectClass=user)(userAccountControl:1.2.840.113556.1.4.803:=32))", "sAMAccountName,distinguishedName,displayname", "Users not required to have a password")
; **********************************************************************************
; Users with any group other than "Domain Users" designated as their "primary" group
; **********************************************************************************
_Examples("(&(objectCategory=person)(objectClass=user)(!primaryGroupID=513))", "sAMAccountName,distinguishedName,displayname", "Users with any group other than 'Domain Users' designated as their 'primary group'")
; **************************************************************
; Users that must change their password the next time they logon
; **************************************************************
_Examples("(&(objectCategory=person)(objectClass=user)(pwdLastSet=0))", "sAMAccountName,distinguishedName,displayname", "Users that must change their password the next time they logon")
; *********************************
; Users that never logged on before
; *********************************
_Examples("(&(&(objectCategory=person)(objectClass=user))(|(lastLogon=0)(!(lastLogon=*))))", "sAMAccountName,distinguishedName,displayname", "Users that never logged on before")
; **************************
; List of all Group Policies
; **************************
_Examples("(objectClass=groupPolicyContainer)", "displayName,gPCFileSysPath", "List of Group Policies")
EndIf

; Close Connection to the Active Directory
_AD_Close()

; **********************************************************
; Executes LDAP queries and displays the results in an Array
; **********************************************************
Func _Examples($query, $fields, $description)

Local $aObjects[1][1]
$aObjects = _AD_GetObjectsInOU($sOU, $query, 2, $fields)
If @error <> 0 Then
MsgBox(64, "Active Directory Functions - Extended Example", "No entries found for LDAP query " & @CRLF & $query & @CRLF & $description & @CRLF & "Error: " & @error)
Else
_ArrayDisplay($aObjects, "LDAP query - " & $description & " - " & $query)
EndIf

EndFunc ;==>_Examples